.TH lha_query 1 "3 February 2009" "TrueCL Commands"

.SH NAME
lha_form \- Form a cluster / add nodes to a running cluster

.SH SYNOPSES
.TS
l l l.
clreq	\fB--application\fP \fIAppname\fP	- Show Application details

clreq	\fB--topology\fP	- Show cluster topology Configuration

clreq	\fB--portmap\fP	- Show port mapping configuration

clreq	\fB--connections\fP	- Show known network info

clreq	\fP--diskhb\fP	- Show disk heartbeat info

clreq	\fP--applist\fP	- Show application summary info
.TE

Other command options available for each of the above commands:

[\fB--xml\fP] [\fB--timeout\fP \fINN\fP] [\fB-lwidth\fP \fINN\fP]

.SH DESCRIPTION
The \fIlha_query(1)\fP command is used to view various items regarding the
cluster configuration. This shows static configuration information - for 
information on the current status of a running cluster use the \fIlha_stat(1)\fP
command instead.

As shown in the command synopsis above, it must take an argument
describing the type of output required.

.SH ARGUMENTS
.TP 4
--application
This will shown the configuration information available for the 
specified application. This includes any timeouts configured, it will
show details of application scripts and of course details of the storage
types, volume groups and  file systems.

An example output might be:

.TS
l.
Application: test
Nodes: node1,node2
Preferred Node: 
Consistency: 
Start Script: /test/data01/bin/start_app
Stop Script: /test/data01/bin/stop_app
Start Timeout: 120
Stop Timeout: 120
Storage: shared
Volume Groups: testdg
Mount point: /test/data01
File System: vxfs
Mount options: log
Vg/Lv: testdg/data01
Size: 25000000
Mount point: /test/data02
File System: vxfs
Mount options: log
Vg/Lv: testdg/data02
Size: 20971520
.TE

So each field is given on a separate line. To be more parse-able the
XML format is probably a better choice:

.TS
l.
<?xml version="1.0" standalone="yes"?>

<lha_application>
    <application name="test" prefnode="" consistency=""
     startscript="/test/data01/bin/start_app" stopscript="/test/data01/bin/stop_app" starttimeout="120"
     stoptimeout="120" nodes="stbe905a,spbe903a" storage="shared" vgs="testdg"/>
    <application_fs mount="/test/data01" fstype="vxfs" options="log"
     vg="testdg" lv="data01" size="25000000"/>
    <application_fs mount="/test/data02" fstype="vxfs" options="log"
     vg="testdg" lv="data02" size="20971520"/>
</lha_application>
.TE

.TP
--topology
This displays which networks are configured on a per-node basis. By default 
the text outuput uses one line per item of output. The output is started with
characteristics of the cluster, for example:

.TS
l.
Cluster: mdb
Port pool: 15000,16000
Echo type: ICMP
Warn time: 40
Fail time: 300
Form time: 120
Heart Beat Interval: 10
Check Topology: 0
Link check frequency: 5
Ip Swap Settle Time: 2
Link Check Reset Time: 60
Maximum Link Failures: 3
Default app Start time: 10
Default app Stop time: 10
Configured DRBD1 Devices: 64
Configured DRBD1 Default Sync Rate: 1024
.TE

Following the cluster characteristics details on a per-node basis are
shown. For each node details of the topologies configured on that node
are shown, for example:

.TS
l.
Node name: node22
OS release: B.11.11
TrueCL release: 0.7.9
IPs: 10.161.2.58
Topology Name: backup
Topology Type: failover
Topology Logical Cards: lan0
Topology Physical Cards: 00:0E:7F:ED:B2:C6
Topology Name: prod
Topology Type: failover
Topology Logical Cards: lan1,lan3
Topology Physical Cards: 00:30:6E:4A:85:36,00:30:6E:4A:75:DD
.TE

When the \fB--xml\fP option is used the output is given in a format 
similar to the following:

.TS
l.
<?xml version="1.0" standalone="yes"?>

<lha_topology>
    <globals name="mdb" portpool="15000,16000"
     echotype="ICMP" interval="10"
     warntime="40" failtime="300"
     topology_check="0" link_check_frequency="5"
     ip_swap_settle_time="2" link_check_reset_time="60" link_maxfails="3"
     def_drbd1_sync="1024" max_drbd1_devs="64"
     defappstart="10" defappstop="10"/>
     <node name="spbe895a" os_level="B.11.11" lha_level="0.7.9" ips="10.161.2.58"/>
     <node_topology node="spbe895a" name="backup" type="failover" lcards="lan0" pcards="00:0E:7F:ED:B2:C6"/>
     <node_topology node="spbe895a" name="prod" type="failover" lcards="lan1,lan3" pcards="00:30:6E:4A:85:36,00:30:6E:4A:75:DD"/>
.TE

.TP
--portmap
This shows the ports allocated to the key cluster daemons. The output is 
very basic:

.TS
l.
15000: Hb Daemon
15001: Stat Daemon
15002: Lock Daemon
15003: Cluster Daemon
15004: Net Daemon
15005: Sync Daemon
15006: Mon Daemon
.TE

Again the \fB--xml\fP option can be used to generate a output more 
suitable for parsing:

.TS
l.
<?xml version="1.0" standalone="yes"?>

<lha_portmap>
  <port number="15000" type="Daemon" detail="Hb"/>
  <port number="15001" type="Daemon" detail="Stat"/>
  <port number="15002" type="Daemon" detail="Lock"/>
  <port number="15003" type="Daemon" detail="Cluster"/>
  <port number="15004" type="Daemon" detail="Net"/>
  <port number="15005" type="Daemon" detail="Sync"/>
  <port number="15006" type="Daemon" detail="Mon"/>
</lha_portmap>
.TE

.TP
--diskhb
Shows information on any configured disk heartbeats. Disk heartbeats
are strongly recommended if shared storage can be made available between 
the nodes. The idea is that if network failures occur SCSI or Fibre-channel
based storage might still be accessible and hence communication to the 
node might be possible to writing to a portion of disk.

The output is given per disk heartbeat, per node. An example of an entry
for a node might be:

.TS
l.
Name: hb1
Key: 12079240140.132599
Node: crxsashpdb01
Device: /dev/vx/rdmp/c28t15d6
Read Offset: 10240
Write Offset: 10752
Validated: 1
.TE

A typical example using the \fB--xml\fP option might be:

.TS
l.
<?xml version="1.0" standalone="yes"?>

<lha_diskhb>
    <hb name="hb1" key="12079240140.132599" validated="1">
       <devinfo node="node1" dev="/dev/vx/rdmp/c102t14d1" read_offset="12288" write_offset="12800">
       <devinfo node="node2" dev="/dev/vx/rdmp/c227t3d4" read_offset="11264" write_offset="11776">
       <devinfo node="node3" dev="/dev/vx/rdmp/c124t11d7" read_offset="15360" write_offset="15872">
</lha_diskhb>
.TE

.TP
--applist
This output shows very highlevel details for applications that are defined
in the current cluster. When run without the \fI--xml\fP option, the
output generated is a tabulated form:

.TS
l.
Name          Validated   vg#  fs#  ip#
app_server01  Y             0    0    0
metasvr       Y             1    2    1
share2        Y             1    1    0
test          Y             1    2    0
.TE

The format of the output is the name of the application, whether it is currently
validated or not, and then the number of volume groups, file systems and IP 
addresses defined for the application.

In XML mode of output the above would appear as:

.TS
l.
<?xml version="1.0" standalone="yes"?>

<lha_applist>
  <app name="lsf_server01" validated="Y" vgs="0" fss="0" ips="0"/>
  <app name="metasvr" validated="Y" vgs="1" fss="2" ips="1"/>
  <app name="share2" validated="Y" vgs="1" fss="1" ips="0"/>
  <app name="test" validated="Y" vgs="1" fss="2" ips="0"/>
</lha_applist>
.TE

.TP
--connections
This shows the details of the "network known connections" defined for the
cluster. This is a series of IP addresses or hostnames that will respond to
ICMP "echo" requests [aka "pings"] when any of the nodes in the cluster
query them.

These are used to ascertain whether a node has lost all network connectivity
or whether the component trying to connect to is no longer available.

The output generated is a simple list of hostnames and the timeout [in seconds]
that is configured for each node. For example:

.TS
l.
Ip Address: remote_external_cluster1
Time out  : 2.5
Ip Address: local_interal_cluster2
Time out  : 0.5
.TE

Again an \fB--xml\fP argument can be combined to generate the output in
XML format instead:

.TS
l.
<?xml version="1.0" standalone="yes"?>

<lha_connections>
  <connection ip_addr="remote_external_clusers1" timeout="2.5"/>
  <connection ip_addr="local_internal_cluster2" timeout="0.5"/>
</lha_connections>
.TE

.TP
--timeout
The amount of time to wait for responses when querying cluster nodes.
If not specified it will default to 5 seconds.

.TP
--xml
This is used to ensure the output sent to the standard output device
appears in XML rather than human-readable format.

.SH OUTPUT
All output, whether in XML or human-readable format is sent to the standard
output device and this can be redirected into a file or piped through into
a script if required.

.SH EXIT CODES
If the information is extracted and returned as expected then a '0' return 
code [for successful will be given]. If the operations
fails completely a failure return code of '1' will occur. 

.SH FILES
Not applicable. All information is taken from the cluster configuration
database present on each node in the cluster.

.SH NOTES
This command is typically used alongside \fIlha_stat(1)\fP to get an
overview of the cluster configuration and current cluster status.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2009, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_stat(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

